<!-- $Id$ -->

<html>
<head>
<title>ESRI ArcSDE Raster</title>
</head>

<body bgcolor="#ffffff">

<h1>ESRI ArcSDE Raster</h1>
<p>
    ESRI ArcSDE provides an abstraction layer over numerous databases that
    allows the storage of raster data.  ArcSDE supports n-band imagery at many bit depths,
    and the current implementation of the GDAL driver should support
    as many bands as you can throw at it.  ArcSDE supports the storage of
    LZW, JP2K, and uncompressed data and transparently presents this through its
    C API SDK.
</p>
<h2>GDAL ArcSDE Raster driver features</h2>
<p>
    The current driver <b>supports</b> the following features:
</p>
<ul>
    <li><b>Read</b> support only. </li>
    <li>GeoTransform information for rasters that have defined it.</li>
    <li>Coordinate reference information.</li>
    <li>Color interpretation (palette for datasets with colormaps, greyscale otherwise).</li>
    <li>Band statistics if ArcSDE has cached them, otherwise GDAL will calculate.</li>
    <li>ArcSDE overview (pyramid) support</li>
    <li>1 bit, 4 bit, 8 bit, 16 bit, and 32 bit data</li>
    <li>IReadBlock support that maps to ArcSDE's representation of the data in the database.</li>
    <li>ArcSDE 9.1 and 9.2 SDK's.  Older versions may also work, but they have not been tested.</li>
</ul>
<p>
    The current driver <b>does not support</b> the following:
</p>
<ul>
    <li><b>Writing</b> GDAL datasets into the database.</li>
    <li>Large, fast, single-pass reads from the database.</li>
    <li>Reading from "ESRI ArcSDE Raster Catalogs."</li>
    <li>NODATA masks.</li>
</ul>

<h2>Performance considerations</h2>
<p>
    The ArcSDE raster driver currently only supports block read methods.
    Each call to this method results in a request for a
    block of raster data for <b>each</b> band of data in the raster, and single-pass requests
    for all of the bands for a block or given area is not currently done.
    This approach consequently results in extra network overhead.  It is hoped
    that the driver will be improved to support single-pass reads in the
    near future.
</p>
<p>
    The ArcSDE raster driver should only consume a single ArcSDE connection
    throughout the lifespan of the dataset.  Each connection to the database has
    an overhead of approximately 2 seconds, with additional overhead that is
    taken for calculating dataset information.  Therefore, usage of the
    driver in situations where there is a lot of opening and closing of
    datasets is not expected to be very performant.
</p>
<p>
    Although the ArcSDE C SDK does support threading and locking, the
    GDAL ArcSDE raster driver does not utilize this capability.  Therefore,
    the ArcSDE raster driver should be considered <b>not threadsafe</b>, and
    sharing datasets between threads will have undefined (and often disastrous)
    results.
</p>

<h2>Dataset specification</h2>
<p>
    SDE datasets are specified with the following information:
</p>
<pre>
 SDE:sdemachine.iastate.edu,5151,database,username,password,fully.specified.tablename,RASTER
</pre>
<p>
<ul>
    <li><b>SDE:</b> -- this is the prefix that tips off GDAL to use the SDE driver.</li>
    <li><b>sdemachine.iastate.edu</b> -- the DNS name or IP address of the server we are connecting to.</li>
    <li><b>5151</b> -- the port number (5151 or port:5151) or service entry (typically <i>esri_sde</i>).</li>
    <li><b>database</b> -- the database to connect to.  This can also be blank and specified as ,,. </li>
    <li><b>username</b> -- username.</li>
    <li><b>password</b> -- password.</li>
    <li><b>fully.specified.tablename</b> -- It is prudent to use a fully specified tablename wherever possible, although it is not absolutely required.</li>
    <li><b>RASTER</b> -- </i>Optional</i> raster column name. </li>
</ul>




</body>
</html>
